/**
 * @file    main.h
 * @brief   Documentation: Main documentation page of WOSH Framework
 ****************************************************************************
 * @author  Alessandro Polo
 * @version 0.8.384 $Id: main.h 2861 2010-08-07 02:42:53Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/

/*! \mainpage WOSH system
 * 
 * WOSH (Wide Open Smart Home) is an open source, cross-platform, message-oriented
 * middleware, written in ANSI C++, designed to enable \b (smart) \b home \b automation.
 *
 * WOSH is a Service Oriented Framework (SOA) providing a (Network) OS independent infrastructure for
 * developing component based software (services, aka bundles); the architecture is inspired by OsGi.
 *
 * WOSH is not a monolithic application, it's rather a \b modular \b library.
 *
 * WOSH is distributed as \b Open \b Source. \ref page_license "Creative Commons BY-NC-SA/3.0"
 *
 * \note This framework is still \c experimental, currently released as preview for developers and expert users.
 *
 * \section page_fundamentals_toc Table of Contents:
 *
 *  - \ref mainpage_state_art
 *  - \ref mainpage_imagine
 *  - \ref mainpage_wosh
 *  - \ref mainpage_features
 *  - \ref mainpage_arch
 *  - \ref mainpage_get
 *
 * \warning Documentation is still transitional from WOSH 0.6.030 [ \b byron ] to WOSH 0.8.499 [ \b icarus ]. Some sections may be out-of-date.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section mainpage_state_art State of the Art
 *
 * Home automation software is a very hot topic. There are few commercial end-user applications
 * (which usually ships with device-packages) to manage a 'smart' home. Such applications
 * are closed, platform-specific.
 *
 * Fortunatly there are many open drivers and applications designed for specific
 * devices and protocols.
 *
 * At time of speaking, there are no real standards in home-automation, multimedia protocols are
 * growing but appliances are still dummy devices and when they can be controlled, it's through a
 * propertary protocol.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section mainpage_imagine Imagine
 *
 * \par Many projects were born from a dream.
 *
 * I imagine my home: interactive, smart, based on open, free systems, designed on inhabitants' needs.
 * 
 * I'll plug new hardware from commercial majors and home-made both, referring to well-known protocols.
 * I'll install new services and hosts that interact each others dynamically.
 * I'll easily setup custom automations when needed, but usually everything will follows my lifestyle without instructions.
 * I'll safely access my home from different communication-channels and locations,
 *  the system also acts as communication router granting privacy to the user.
 * I'll control my computers and any devices through stardard interfaces, no matter their
 *  low-level protocol or architecture.
 *
 * My home is smart and will learn my attitudes, preferences, my own lifestyle.
 *
 * As Developer, I imagine that the dream is enabled by a software: \b framework (middleware).
 *
 * I may think on something like \c OsGi, with <tt>.NET</tt> or \c Java capabilities, but in C++.
 *
 * I dreamed \b WOSH.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section mainpage_wosh WOSH
 *
 * WOSH (Wide Open Smart Home) is an open source, multi-platform framework
 * (message oriented middleware) written in ANSI C++, designed to enable (smart) home automation.
 * WOSH is a Service Oriented Framework (SOA) providing a (Network) OS independent infrastructure
 * for developing component based software (services, aka bundles), but it ships with many implemented
 * services and some end-user applications (as woshsrv, WorkShop). 
 *
 * Some reasons to use and join the WOSH projects are:
 *  - It's free, open source, alive!
 *  - It's modular and growing
 *  - It's easy to plug-in new features (C++ required)
 *  - It has been though to be efficient and intuitive
 *  - It links with state-of-the-art libraries (QT4, gloox, curl, festival, gstreamer010, ..)
 *  - It comes with many built-in services (networking, communication, entertainment, remote control, ..)
 *
 * \see \ref page_config "Configure the WOSH system"
 * \see \ref page_run "Running WOSH for first time"
 * \see \ref page_using "Using WOSH.. some use-cases"
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section mainpage_features WOSH Features
 *
 * Some examples of what WOSH offers are explained in section \ref page_using "Using WOSH".
 * Many features depends on hardware devices (such as X10 control), media playback,
 * telephony. Most important features for end-user are:
 *
 *  - Built-in end-user \c applications: console (CLI) and graphical (multiplatfom GUI) both
 *
 *  - \c Distributed computing, minimal configuration networking
 *
 *  - \b Multi-user, role based access
 *
 *  - \b Remote \b control using Instant Messaging (using \c libgloox; compatible with GTalk),
 *    SMS (send/receive) and call monitoring (on Windows-Mobile, RNDIS connected smart phone)
 *
 *  - \b Appliances and \b sensors (X10 devices) monitor/control (on POSIX, based on \c Heyu)
 *
 *  - \b Entertaiment, multi-zone media playback (using \c GStreamer on POSIX or QT \c Phonon on
 *    Windows, \c VLC). Media-Director service provides a high abstraction layer, 
 *    the recovery/guess multimedia status, hardware/software shortcuts and more
 *
 *  - Centralized \b Communication system (selecting best communication channel), using
 *    also interpreters (such as Festival for Text2Speech)
 *
 *  - Building \b abstract-representation of the home and its devices (floor, rooms, lights, audio-box, ..)
 *
 *  - TaskManager service, providing support for basic every-day tasks (CronJobs and \b Automation)
 *
 *  - Windows Mobile tiny-server, to enable (SMS) messaging and call monitoring
 *
 *  - Weather service, import condition and forecast into the system
 *
 *  - Monitor DSL connection (on POSIX, based on pppstats)
 *
 *  - many not listed and more to come..
 *
 *  - Garderner service, handles garden irrigation
 *
 *  - Big-Brother service, which recognizes users and their location
 *  - Butler service, providing common services in a smarter way than event-based automations
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section mainpage_arch WOSH Architecure
 *
 * \ref page_applications "WOSH Applications" (as servers, front-ends, ..) ship with a wosh::WoshKernel singleton
 * and act as one (idempotent) host of the WOSH network (in other words: peer-to-peer), WoshKernel is a
 * microkernel hosting a limited number of core-services (such as wosh::NetworkManager, wosh::UserManager,
 * wosh::BusManager, ..).
 *
 * Bundles and many internal components are loaded dynamically at run-time (often
 * on first use) and implement (shared, well-known) interfaces. Object allocation and type-recognition
 * is a custom, extended RTTI model, supporting multiple-inheritance trees and class-versioning ).
 * WOSH concurrency model is (very) asynchronous and multi-tasking.
 *
 * WOSH provides (almost) a zero-configuration networking, run-time protocol loading/setup.
 * Kernel, Core-Services and wosh::Bundle may cooperate and exchange information only by passing
 * messages.
 * Messaging mode follows a weak publish/subscribe model. Message handlers (such as
 * Bundles) may connect to one or more wosh::Bus(ses) and receive messages (FIFO per Bus), messageposting
 * is totally asynchronous. Actually, message-delivery contract is (very) weak: no
 * ACKs/retransmissions; within a private BusRing, message-ordering is [FIFO, total, but not virtually
 * synchronous (view changes are applied immediately)], but generally unpredictable (because of
 * network and intra-bus routing).
 * In short: messages are very similar to UDP datagrams.
 * 
 * wosh::Message has a source/destination (wosh::URI, supporting regex) and generic content-template
 * (mostly: wosh::Request, wosh::Response, wosh::Fact, wosh::Notification).
 * Destination/Content filtering is implemented within the
 * listener itself (not by the dispatcher). Delivery is usually iterative and non-fault-tolerant.
 * 
 * Messages may be routed transparently (and optimized by the framework) between Bus(ses) and
 * hosts of the network. In other words, a "medium" level of location transparency is provided.
 * \ref page_core_network "WOSH Networking" is based on host-discovery, provided by a generic Discovery service
 * (actually implemented on-top of UDP). Discovery datagrams hold information required to setup a connection
 * and some optional information for optimized routing strategies (such as neighbours list).
 * NetworkManager monitors channels (connections) and creates new links (intersecting supported
 * protocol-strings, such as TCP://192.168.0.1:7878). Message (de)serialization is implemented by
 * another core-component. Message transmission is always point-to-point, supporting multi-hop
 * based on static and dynamic routing tables. BusManager and NetworkManager cooperate using
 * two (asynchronous) wosh::MessageQueue(s).
 * 
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section mainpage_get Get WOSH
 *
 * WOSH is a multi-platform software, tested on POSIX, Windows, Windows-Mobile and compatible with MAC-OS, you
 * may find links to online repositories on \ref page_distribution.
 * First updated repository is hosted on <a href="https://sourceforge.net/projects/wosh/files/">SourgeForce</a>.
 *
 *
 ****************************************************************************
 * @todo [..]
 */
